--------------------------------------------------------------------------------
--------------------------------------------------------------------------------

  Author: Eric Gessner

    Date: 6/5/97

   Email: 75700.1057@compuserve.com

          NOTE: Any/all feedback will be appreciated.
                I'm looking for a new job if you can help please let me know.

          This document describes a C++ DirectX error handler. It may or
          may not be helpful to you (check it out). I coded it to be portable.
          I used standard include files, functions, and data types.
          I included the source files (dxerror.cpp, .h). I intended for this to
          be compatible with most C++ compilers (if its not you have the src).

--------------------------------------------------------------------------------
  CONTENTS
--------------------------------------------------------------------------------

  1) OverView/Purpose.
  2) Files Provided.
  3) Design Notes.
  4) Error Types and Amplifying Data Constraint.
  5) Examples/Use.

--------------------------------------------------------------------------------
1. OverView/Purpose.
--------------------------------------------------------------------------------

   This DirectX error handler was written in C++ and is designed for use with
   the DirectX 3. The file containing the error data (dxerror.dat) contains
   data derived from error constants, error values, and helpfile information for
   DirectX 3. You (*)may be able to use it for previous versions of DirectX.

   This DirectX Error Handler Provides the following functionality:

	1) Lookups Up DirectX error data (contained in a file) for the error.
	2) Display a MessageBox with the following information:
             a) The constant identifier (e.g. "DDERR_ALREADYINITIALIZED").
	     b) A description of the error (as contained in the help file).
             c) Amplifying Data (user supplied amplifyies origin or nature).
        3) The error handler will automatically call a user supplied clean up
			  function (when a clean up function supplied).

 (*)Note: DirectX 3 represents the error values (most of them)
          in 32 bit format. The error data is formatted via calls to a DirectX
          MAKE_DDHRESULT() macro which in-turn calls Windows MAKE_HRESULT()
          macro. (MAKE_DDHRESULT is defined in the dx header files and
          MAKE_HRESULT() is defined in winerror.h, see dx header files and
          winerror.h for details). If this method has changed from earlier
          DirectX versions this Error Handler won't work with them because the
          values used to retrieve error information are based on the method
          described above).

--------------------------------------------------------------------------------
2. Files Provided.
--------------------------------------------------------------------------------

     You need 3 files dxerror.cpp, dxerror.h, and dxerror.dat.
     The DxErrorHandler::GetErrorData() member function expects the dxerror.dat
     to be in the current/working directory.

               FILES          DESC
           ---------------   ----------------
          (1) dxerror.h    - header file.
          (2) dxerror.cpp  - source file.
          (3) dxerrors.dat - error data file.
          (4) dxerror.lib  - Borland Ver 5.01 library.
          (5) errordoc.txt - this file.

--------------------------------------------------------------------------------
3. Design Notes.
--------------------------------------------------------------------------------

   DxError was designed to encapsulate functionality for an error.
   DxErrorHandler was designed to encapsulate handling DxErrors.
   These classes can be easily modified to extend the error handling
   capability.

--------------------------------------------------------------------------------
4. Error Types and Amplifying Data Constraint.
--------------------------------------------------------------------------------

   The following DxErrorTypes are defined.
   ---------------------------------------
   DXERR_FATAL
   DXERR_WARNING
   DXERR_ANYERROR

   Use 60 Characters Maximum for Amplifying Data.
   ----------------------------------------------
   MAX_DXERR_AMPLIFYING_DATA_LEN 60

--------------------------------------------------------------------------------
5. Examples/Use.
--------------------------------------------------------------------------------

   Error information is obtained via a call to the HandleDxError() member
   function. The HandleDxError() member function takes up to 4 (four)
   parameters:

   Parameter   Description
   ---------   ----------------------------------------------------------------
     p1       	The DX error value (the result returned from the DX function).
     p2			The DxErrorType (DXERR_FATAL, DXERR_WARNING, or DXERR_ANYERROR).
     p3        Amplifying Data (something meaningful like its origin, etc).
     p4        Function to Call (the function you want to call if error occurs).


   Overloaded HandleDxError Function   (call it passing desired params)
   ---------------------------------
   MyErrHandler.HandleDxError(p1);
   MyErrHandler.HandleDxError(p1, p2);
   MyErrHandler.HandleDxError(p1, p3);
   MyErrHandler.HandleDxError(p1, p4);
   MyErrHandler.HandleDxError(p1, p2, p3);
   MyErrHandler.HandleDxError(p1, p2, p4);
   MyErrHandler.HandleDxError(p1, p3, p4);
   MyErrHandler.HandleDxError(p1, p2, p3, p4);


   ----------
   EXAMPLE 1:
   ----------

      #include "dxerror.h"   //include the header and make sure the compiler can
                             //find the dxerror.lib file to link in.

      void MyFunction()
      {
        LPDIRECT3DRM lplpD3DRM;
        HRESULT dxresult;    //HRESULT is DWORD, 32 bits for the result

        dxresult = Direct3DRMCreate(&lplpD3DRM);
        if (dxresult != D3DRM_OK)
        {
          DxErrHandler dxeh;            //create an instance of an error handler
          dxeh.HandleDxError(dxresult); //call it to handle the error
        }
      }

   ----------
   EXAMPLE 2:
   ----------

      #include "dxerror.h"   //include the header and make sure the compiler can
                             //find the dxerror.lib file to link in.

      void MyFunction()
      {
        LPDIRECT3DRM lplpD3DRM;
        HRESULT dxresult;    //HRESULT is DWORD, 32 bits for the result

        dxresult = Direct3DRMCreate(&lplpD3DRM);
        if (dxresult != D3DRM_OK)
        {
          DxErrHandler dxeh;            //create an instance of an error handler
                                        //call it to handle the error
          dxeh.HandleDxError(dxresult, DXERR_FATAL ,"MyFunction Failed");
        }
      }

  ----------
  EXAMPLE 3:
  ----------

      #include "dxerror.h"   //include the header and make sure the compiler can
                             //find the dxerror.lib file to link in.

      void MyErrorFunct()    //function to call if error occurs
      {
         //code
      }

      void MyFunction()
      {
        LPDIRECT3DRM lplpD3DRM;
        HRESULT dxresult;    //HRESULT is DWORD, 32 bits for the result

        dxresult = Direct3DRMCreate(&lplpD3DRM);
        if (dxresult != D3DRM_OK)
        {
          DxErrHandler dxeh;            //create an instance of an error handler
                                        //call it to handle the error
          dxeh.HandleDxError(dxresult, MyErrorFunct);
        }
      }
   ----------
   EXAMPLE 4:
   ----------

      #include "dxerror.h"   //include the header and make sure the compiler can
                             //find the dxerror.lib file to link in.

      void MyErrFunct()    //function to call if error occurs
      {
         //code
      }

      void MyFunction()
      {
        LPDIRECT3DRM lplpD3DRM;
        HRESULT dxr;    //HRESULT is DWORD, 32 bits for the result

        dxr = Direct3DRMCreate(&lplpD3DRM);
        if (dxr != D3DRM_OK)
        {
          DxErrHandler dxeh;            //create an instance of an error handler
                                        //call it to handle the error
          dxeh.HandleDxError(dxr, DXERR_FATAL ,"MyFunction Failed", MyErrFunct);
        }
      }


--------------------------------------------------------------------------------
  Author: Eric Gessner

   Email: 75700.1057@compuserve.com
          (any/all feedback will be appreciated).
--------------------------------------------------------------------------------
